Container and Signature Service

Introduction

Container And Signature Microservice is service from Signing Services collection that organizes such important features as:

• Signing container related actions:
  • Create signing container
  • Update signing container
  • Download signing container attachments
  • Download signing container
  • Get information about signing container
    • Sign container / PDF using qualified signature tools such as:
      • ID card
      • Smart-ID
      • Mobile-ID
      • E-Paraksts Mobile (ePM)
        • Sign PDF using non-qualified visual signature

Package content

• Microservice package location: /DMSS/dmss-container-and-signature-services/.
• Microservice delivery package includes separate folder for each microservice having same name as microservice executable .jar file. Each microservice has configuration application.yml file that should be adjusted to fit client needs.

Container Microservice package (folder dmss-container-and-signature-services) includes:

• dmss-container-and-signature-services.jar – java archive package file. More details about JAR file format could be found here: https://en.wikipedia.org/wiki/JAR_(file_format)
• application.yml – archive service configuration file. More details about .yml file format could be found here: https://en.wikipedia.org/wiki/YAML

DMSS General Architecture

Digital Mind Signing Services (DMSS) is a collection of REST webservices. DMSS core services devloped based on Java Spring Boot framework. DMSS consists following core services (collections of specific functionalities):

• DMSS Archive Services – REST Services for interfacing with various archive/storage systems. Main purpose is to put and retrieve documents to and from storages. Depending on archive type set of features can be extended to support versioning and metadata manipulations.
• DMSS Archive Services Fallback Service – REST Services to store documents with requests in versioned folders generated by service. Service can be used in case main archive is down or in maintenance, documents and requests stored temporarily in fallback service. Once main archive up and running again documents automatically moved to main archive. Fallback service can be used as main archive as well. It means document will be stored in filesystem and document id generated by service.
• DMSS Filesystem Archive Service – REST Services to store and retrieve documents from filesystem by document paths.
• DMSS Document Generation Services – REST Service for generating document form input json data compiled with predefined template. Service includes FOP and BIRT template engines.
• DMSS Digital Stamping Service – A service to interface certificate access from USB devices or HSM service providers.
• DMSS Container and Signature Services – REST Services to create, sign, extract container type and pdf documents.
• DMSS Process and Audit Service – REST Services to store signing workflow and events auditing records.
• DMSS Internal Portal Proxy Service – REST Services for proxy internal portal requests to backend services like „Container and Signature Service“, „Process and Auditing Service“.
• DMSS Authentication Service – REST Services for authentication including support for ID-Card, Mobile-ID and Smart-ID.

Document signing process diagram

Configuration

In YAML configuration whitespace indentation is used for denoting structure. Table below is showing Container Microservice application.yml configuration parameters based on indent amount that could be used to configure microservice for a client needs:

Name	Description	Example value
server.port
spring.servlet.multipart.maxFileSize	File size that could not be exceed for servlet requests.	100Mb
spring.servlet.multipart.maxRequestSize	Total request size that could not be exceed for servlet requests.	100Mb
spring.servlet.multipart.max-file-size	File size that could not be exceed for servlet requests.	100Mb
spring.servlet.multipart.max-request-size	Total request size that could not be exceed for servlet requests.	100Mb
spring.sleuth.web.client
spring.main.allow-bean-definition-overriding
signatureServices.signatureIsAdded AsynchronouslyToContainer	Signature is added synchronously to container.	false
signatureServices.timeout
signatureServices.cors.disabled	Cross-Origin Resource Sharing status.	false
containerController.illegalChars	Illegal character for container name.	[\\\\/:*?"<\\>^&]
containerController.createNewContainer.documentData.containerExtensionJsonKey
containerController.createNewContainer.documentData.certInHexJsonKey
containerController.createNewContainer.documentData.signatureProfileJsonKey
containerController.createNewContainer.documentData.documentFilenameJsonKey
containerController.createNewContainer.documentData.documentMimeTypeJsonKey
containerController.createNewContainer.documentData.containerMimeTypeJsonKey
containerController.createNewContainer.documentData.documentTypeJsonKey
containerController.createNewContainer.documentData.objectNameJsonKey
dmss-archive-services.baseUrl	Archive service url.	http://localhost:8090/api
dmss-archive-services.fallbackUrl	Fallback service url.	http://localhost:8086/api
dmss-arhcive-services.forwardHttpHeaders	List of forwarded http headers.	OTCSTICKET, x-user-context
dmss-archive-services.configuration.container.defaultMimeType	Default MIME type.	application/vnd.etsi.asic-e+zip
dmss-archive-services.configuration.container.defaultContainerExtension	Default container extension.	.bdoc
dmss-archive-services.configuration.container.defaultDocumentType
dmss-archive-services.configuration.dataToSign.mimeType
dmss-archive-services.configuration.dataToSign.documentType
dmss-archive-services.configuration.dataToSign.fileExtension
dmss-archive-services.saveBinFilesAlwaysInFallback
dmss-archive-services.fileMimeTypesAndExtensions	mime.types file path.	D:/DMSS/dmss-container-and-signature-services_V2/mime.types
smartId.hostUrl	Smart-ID service host url.	https://rp-api.smart-id.com/v1
smartId.relyingPartyUUID	Client ID that should registered and received from SK.	00000000-0000-0000-0000-000000000000
smartId.relyingPartyName	Company name that would be shown in Smart-ID popup.	Digital Signing
smartId.vcChoice
smartId.displayText	Extra text that would be shown in Smart-ID popup.	“Please sign!”
smartId.delay
mobile-id.truststorepath	Path to trusted certificated.	D:/DMSS/dmss-container-and-signature-services_V2/mobid.jks
mobile-id.fakeRequestsInTest	Allowing fake requests in test mode.	true
mobile-id.fakeReplacements.- idCode
mobile-id.fakeReplacements.replacementIdCode
mobile-id.fakeReplacements.replacementPNO
mobile-id.countries.EE / LT / LV
mobile-id.countries.EE / LT / LV.relyingPartyName	Company name that would be shown in Mobile-ID popup.	Digital Signing
mobile-id.countries.EE / LT / LV.hostUrl	Mobile-ID service url.	https://tsp.demo.sk.ee/mid-api
mobile-id.countries.EE / LT / LV.relyingPartyUUID	Client ID that should be registered and received from SK.	e18e72f7-4e7d-4e13-a309-82695135de2c
mobile-id.countries.EE / LT / LV.displayText	Extra text that would be shown in Smart-ID popup.	“Please sign!”
hsm.pkcs11ModulePath
hsm.partitionPin
hsm.slotIndex
dmss-document-generation-service.baseUrl	Document generation service url.	http://localhost:8083/api
dmss-document-generation-service.configuration.defaultMimeType	Default MIME type.	application/pdf
dmss-document-generation-service.configuration.defaultExtension	Default extension.	.pdf
dmss-digital-stamping-service.baseUrl	Digital stamping service url.	http://localhost:8084/api
hystrix.command.default.Execution -> isolation -> thread -> timeoutInMilliSeconds
digidoc4j.configuration.mode
digidoc4j.configuration.file
digidoc4j.configuration.preferAiaOcsp
digidoc4j.configuration.issuers.name url keystore password alias preferAiaOcsp	digidoc4j issuer list.	name: "E-ME SI (CA1)" url: "http://ocsp.sk.ee/_proxy" keystore: "" password: "" alias: "" preferAiaOcsp: false
pdf.signature.defaults.xAxis	Signature X Axis location.	100
pdf.signature.defaults.yAxis	Signature Y Axis location.	100
pdf.signature.defaults.zoomPercent	Zoom percent value.	50
pdf.signature.defaults.signatureText	Signature text.	"Digitally signed by: {cn} \n{dnName} \nAt date: {date}"
pdf.signature.textImage.by		Signed By
pdf.signature.textImage.in		In
pdf.signature.textImage.by		At
pdf.watermark.defaults.xAxis	Signature X Axis location.	100
pdf.watermark.defaults.yAxis	Signature Y Axis location.	700
pdf.watermark.defaults.transparency	Transparency level (0.0 – 1.0).	1
pdf.watermark.defaults.colour r g b	Color RGB values.	r: 255 g: 0 b: 0
pdf.watermark.defaults.font	Font path.	"C:/Users/Brain/font/Pacifico-Regular.ttf"
pdf.watermark.defaults.fontsize	Font size.	50
hazelcast.expireInMinutes
hazelcast.members
hazelcast.port	Hazelcast port.	5777
hazelcast.kubernetes.enabled	Kubernetes enabled status.	true
hazelcast.kubernetes.service-dns	Kubernetes service dns.	dmss-container-headless.default.svc.cluster.local
idCard.useContainerIdAsSesssion	Use container ID as session.	true
lvrtc.baseUri	LVRTC service address.	https://eidas.eparaksts.lv/
lvrtc.clientId	ePM user ID.	digimind
lvrtc.clientSecret	Client secret provided by LVRTC.	MbK4X6drcyKrJy4Q
lvrtc.authRedirectUri	ePM auth redirect URI.	https://demo.trustlynx.com/identity?return=true
lvrtc.signRedirectUri	ePM sign redirect URI.	https://demo.trustlynx.com/portal/
lvrtc.defaultLocale	Default ePM language.	lv
lvrtc.tspUrl	Time stamp provider URL.	https://tsa.eme.lv/
lvrtc.keystorePassword	Keystore password.	DigitalMind
lvrtc.certAlias	Certificate alias.	ecm.digitalmind.lv (eparaksts ica 2017)
lvrtc.keystorePath	Keystore path.	D:/DMSS/dmss-container-and-signature-services/digitalmind.jks
lvrtc.certtruststorePath	KCertificate trust store path.	D:/DMSS/dmss-container-and-signature-services/cert.truststore.jks
logging.config	Log file configuration XML path.	D:/DMSS/dmss-container-and-signature-services /logback.xml
logging.level.root	Logging level.	info / debug / trace.

Common usage scenarios, API sequence

Create container from existing document (Archive Microservice) and initiate Smart-ID signing (Container Microservice)

Creating container API:

• POST /api/document/create (Archive Microservice)

Input parameters:

• file (formData) – file or files array will be added to container
• documentData (formData) – JSON structure describe in section “Common JSON structure for document creation”.

Request example:

Response:

• JSON data including document id

<CreateDocumentResponse>
    <id>cab7ae37-560f-43ab-9c9a-477c0dcce4ca</id>
    <externalid>64b6c4cf-f4e5-42cf-8095-a42ce2e88c00</externalid>
</CreateDocumentResponse>

As the result of operation we have created container from external file / files and this container has been saved in Archive with specific ID cab7ae37-560f-43ab-9c9a-477c0dcce4ca. Now, using this ID we could initiate Smart-ID signing operation.

Initiate Smart-ID signing API:

• PUT /api/signing/smart/container/{id}/sign (Container And Signature Microservice)

Input parameters:

• id – container ID in Archive
• signRequest – JSON structure with fields that are necessary for Smart-ID signing initiation

Request example:

Response:

{ 
result: 'SIGNING_STARTED',
sessionCode: 'acbf589d-c634-4942-a08d-5460181c3fa5',
verificationCode: '0204' 
}

After this we need to poll Smart-ID session status API in order to understand what is the result of operation. There are multiple scenarios possible like user enters correct PIN / user refuses to enter PIN / timeout e.t.c.

Polling Smart-ID session API:

• GET /api/signing/smart/session/{session}/status

Input parameters:

• session – Session code that was received during Smart-ID signing initiation function

Request example:

Response:

{
result: ‘SIGNING_COMPLETED’
}

Status SIGNING_COMPLETED means the document was successfully signed.

Document download from Archive

Document downloading API:

• GET/api/container/{id}/download

Input parameters:

• Id (path) – document id

Request example:

GET https://riga-app.digitalmind.lv:82/api/container/754c4c7e-18c2-4e3b-8607-4be39591bf5c/download

Response:

• File if successful.

Running

It is recommended to use OpenJDK 11 (typically installed at /usr/lib/jvm/java-11-openjdk) for microservices execution.

Service execution command:

java -jar /opt/DMSS/ dmss-container-and-signature-services/

dmss-container-and-signature-services.jar --spring.config.location=/opt/DMSS/

dmss-container-and-signature-services /application.yml

These commands could be organized to run simultaneously as service / task scheduler based on OS and its possibilities (at example for windows – service startup commands could be organized in powershell script running on a system startup, for Linux – background service). The way how these commands are organized for running is decided individually by solution owner.

Debugging

In section 3 microservice has logging -> config setting that defines path to logback.xml file. This XML file has an appender section that defines the location of log files. Example of such section is:

In current example logs are stored inside /opt/DMSS/logs/ folder. To define logging level for specific microservice, open corresponding application.yaml file and change logging -> level -> root setting to info* / debug / trace based on needs.

External resources

Container microservice is using signing tools like SmartID, ePM e.t.c. that require access for external resources. It is important to have some web address based services available to be accessed from a machine where the solution is delivered. This list could be potentially changed as soon as each tool authority could change their service addresses, but typically we are informed some time before it happens. Current address and port list that should be opened from a microservice machine is:

• Ports 80 and 443:
  • 82.140.152.1 elektroninisparasas.lt
  • 62.65.42.57 rp-api.smart-id.com
  • 147.67.34.30 ec.europa.eu
  • 212.70.163.131 trustlist.gov.lv
  • 62.65.42.42 ocsp.sk.ee
  • 195.80.123.217 sr.riik.ee
  • 62.65.42.41 mid.sk.ee
  • 62.65.42.51 tsa.sk.ee
  • sk.ee
  • c.sk.ee
  • sk.ee
  • aia.sk.ee
  • ocsp.eparaksts.lv
  • ocsp.eme.lv
• Ports 80, 443 and 389
  • *.eme.lv

Document Changelog

Version	Changes	Date	Changed By
v1.0.0	Initial version of User Manual	25.08.2021	Mihails Gordijenko